home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1997 April
/
EnigmA AMIGA RUN 17 (1997)(G.R. Edizioni)(IT)[!][issue 1997-04][EAR-CD].iso
/
EARCD
/
comm
/
mail
/
YamNet.lha
/
rexxtra12.lha
/
RexxExtra.doc
next >
Wrap
Text File
|
1990-04-29
|
16KB
|
480 lines
RexxExtra
---------
Documentation on the rexxextra.library (Version 1.2)
Date: March 18, 1990
Introduction
------------
rexxextra.library is an ARexx external function library. It's
purpose is to extend the string manipulation and mathematical
capabilities of ARexx by defining new functions.
This library is intended for users of ARexx, the Amiga
implementation of the high level language by William S. Hawes,
who wish to expand the set of functions available, just as the
libraries supplied with ARexx (rexxsupport, rexxarplib, and
rexxmathlib.library) add new functions.
Archive Contents
----------------
The following files should be contained in this archive file.
File Size Description
----------------- ----- -----------
rexxextra.library 7060 The ARexx library. Copy to libs:
RexxExtra.doc 16226 This file. This size may vary some.
Test.rexx 3946 Exercises and verifies the library
functions
rexx/ directory 37960 Example programs (approx.)
Please distribute the library archive only in it's original
form, without changes or additions. If possible, when uploading
to a BBS, name the archive RXXTRA12.LZH so we may all know
which version it is.
Although WShell (also by Mr. Hawes), an Amiga command shell, is
not needed to use RexxExtra, all example programs have only
been run under WShell, so these may have to be modified to run
under your own shell. Probably by adding "address command" in
front of any CLI callable command strings.
Installation
------------
First, copy the included rexxextra.library file to your libs:
directory. The size is only about 7K.
copy rexxextra.library libs:
Adding the library to ARexx
---------------------------
The functions are available to any ARexx program once the
command:
call addlib 'rexxextra.library',-20,-30,0
has been issued in any Arexx program. This only need be done
once per session (I do all mine at bootup, then I don't have
to worry about it). The included ARexx programs contains this
step.
Description of library functions
--------------------------------
Basically, you've now got some new functions available you can
call from any ARexx program. More are being added, so this list
will grow in the future.
o Replace() - replace one string with another throughout a
third.
o Sortwords() - sorts string of words into alphabetical order.
o Cparse() - "parse" a command line.
o Fparse() - "parse" a file name.
You also have some example ARexx programs using and testing
these functions.
Following is a detailed description of each of the functions.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Replace - replace one string with another in a string
-------
Syntax
======
string4 = Replace(string1,string2,string3,['Case'])
string1 is the string to replace with.
string2 is the string to look for.
string3 is string to perform replacment on.
'Case' is an optional argument and, if supplied, case will be
ignored when searching for string2 in string3.
string4 is returned value when all string2's have been replaced
by string1's in string3.
Description
===========
This function was the first one I tried the library out with,
and its such a simple and useful function, I decided to leave
it in.
Restrictions
============
The result string cannot be longer than 10 times string3. If
anybody knows of a good way to compute the length needed for
the result string before doing the replace, let me know.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Sortwords - sort a string of words
---------
Syntax
======
string2 = SortWords(string1)
string1 is list of words to sort
string2 is sorted string1
Description
===========
This function will returns its argument, which is a string of
words, into ascending alphabetical order. Currently, the space
is the only delimiter for words.
As with ARexx itself, string1 and the returned string are
limited to about 65,500 characters.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Cparse - parse a command line
------
Syntax
======
string = Cparse(commandline,template,stem)
commandline is as recieved from the user, ie, "parse arg
commandline".
template is standard AmigaDOS/ARP command template (with
extensions), ie, "Q=QUICK/S,BUF=BUFFER/K,FROM,TO/A". Note: Any
single keyword should not be more than 30 characters.
stem is the name of the stem variable to use for the compound
variables to create. You might want to keep this relatively
short, especially if you're getting many arguments from the
command line. You do not need to include the ending period.
Description
===========
This function allows you to quickly and easily determine the
input to your ARexx program, and "parse" the command line into
a whole set of user-defined variables. This gives your ARexx
programs the power of AmigaDOS/ARP command parsing with one
function call.
You supply to the function in a standard AmigaDOS/ARP template
format (with certain extensions) what to expect on the command
line. The function scans the command line, determining what
flags, arguments, qualifiers and such are present, and returns
a "program string" (a string suitable for INTERPRETing)
containing the commands neccessary to assign values from the
command line to variables in the program. Got that? Well,
fortunately using Cparse is simpler than explaining it.
For instance, we want to write an ARexx program that accepts
the same arguments as the LIST command. Let's call it TREE. The
TREE command has a template of:
DIR,P=PAT/K,KEYS/S,DIRS/S,FILES/S,SORT/S,SINCE/K,UPTO/K,
DATES/S,NODATES/S,SUB/K,BLOCK=BLOCKS/S,NOHEAD/S,LFORMAT/K
This function will fill in args.DIR, args.P, args.KEYS,
args.DIRS, etc. from the supplied command line. Arguments,
qualifiers, and flags may appear on the command line in any
order, just as with AmigaDOS/ARP. Command lines are verified
for missing arguments, and a variable is assigned a severity
level (0...2) so you can determine the the error, if any.
You must format the template in this order: flags (/S),
qualifiers (/K), arguments (/A & /R) and optional arguments
(in the order to expect them from the user), then lists (/...
& /L). For example, the TREE command would pass a template of:
KEYS/S,DIRS/S,FILES/S,SORT/S,DATES/S,NODATES/S,BLOCK=BLOCKS/S,
NOHEAD/S,SINCE/K,UPTO/K,P=PAT/K,SUB/K,LFORMAT/K,DIR
You must also decide on a stem variable name before calling
this routine. You may assign values to the compound variables
for default responses (except switches); these will not be
changed if that option is missing from the command line.
Switches will always be in the returned string, and will always
be a boolean value.
Synonyms for keywords (those following an "=" in the template)
are supported, but the assigned variable will always be the
keyword on the LEFT of the equals sign.
If, after resolving all template tokens, there is still some
commandline left, a variable "stem.REMAIN" is added equaling
what's left. Consequently, you may find it difficult to use
"REMAIN" as a keyword in your template.
A variable, "stem.ERRCODE" is added indicating if any errors
were encountered while parsing the commandline. If errors are
encountered, another variable "stem.ERRTEXT" is also added to
explain the error. Consequently, you may find it difficult to
use "ERRCODE" and "ERRTEXT" as keywords in your template.
Either single or double quotes are recognized for delimiting an
argument containing spaces. However, the "double quoting"
convention (two quotes in a row to denote one in the string) is
not accepted.
In summary,
token variable description
----- -------- -----------
FLAG/S stem.FLAG 1 if present, 0 if not.
QUALIFIER/K stem.QUALIFIER value of following string
or not changed if not present.
ARGUMENT/A stem.ARGUMENT value of following string if
keyword present, first string found
after removing flags and qualifiers
if not.
ARGUMENT/R same as /A but keyword is required
ARGUMENT stem.ARGUMENT value of first string found
after removing flags and qualifiers
LIST/... stem.LIST.0 count of items in list. 0 if none.
stem.LIST.1 list items
thru
stem.LIST.n
LIST/L same as /... but list is required.
stem.REMAIN remainder of command line after all
tokens have been parsed out
stem.ERRCODE 0 if no errors parsing commandline
1 if remainder but no other problems
2 if required argument missing or
qualifier keyword specified w/o
value
stem.ERRTEXT explanation of error (currently if > 1)
Note: The AmigaDOS tempate structure of multiple commas
(",,,,,,,") is not supported.
Using Cparse
============
There are probably many ways Cparse could be used, but here's what
I do. This adds complete interactive command line parsing to any
ARexx program. In each ARexx program I want to add command parsing
capabilities to, I start with or add this "template" and modify to
suit.
This template contains statements to do the preliminary work for
Cparse, such as handling "?" on the command line, presenting a
template to the user, showing additional help upon entry of a
second "?", calling the Cparse function, and exiting if an invalid
command line is found.
The user may request additional help by entering a second "?" at
the display of the template. The program will display help
information contained in the source code of the program. Place
this "self-documenting" help using a comment in the ARexx
program. The beginning of the comment must be the third source
line, and continues until a close comment is found.
---------------------------------------------------------------
/* typical.rexx */
/*
Typical ARexx program using Command Line Parsing
and help system
USAGE: TYPICAL [FROM] <file> [TO <dir>] [QUIET]
*/
dtemplate = 'FROM/A,TO/K,QUIET/S' /* template displayed to the user */
template = 'QUIET/S,FROM/A,TO/K' /* template supplied to Cparse */
args.='' /* stem variable to use */
parse arg g_c
do while g_c='?'
options prompt dtemplate
parse pull g_c
if g_c='?' then do
g_s=sourceline(3)
if pos('/*',g_s)=0 then break; if pos('*/',g_s)>0 then break
say
g_s=sourceline(4)
do i=5 while pos('*/',g_s)=0; say g_s; g_s=sourceline(i); end
say
end
end
interpret Cparse(g_c,template,'args')
if args.ERRCODE > 1 then do; say args.ERRTEXT; exit 5; end
/*
This is the body of the program, that would actually do
something. From here on in the program, ARGS.FROM, ARGS.TO, and
ARGS.QUIET will contain the values from the command line.
*/
exit 0
---------------------------------------------------------------
Or, of course, you can figure out your own way to use it.
Example programs
================
I've included many example programs illustrating the above in
this release. The programs are also useful in their own right.
Limits
======
Variable names (keywords in the template) are limited to 30
characters. Stem variable names should be reasonably short,
perhaps less than 8 characters. The returned string is limited
to 1023 characters. If this isn't long enough, I can change it.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Fparse - parse a file name
------
Syntax
======
string = Fparse(start_dir,filespec,[defaultspec],
[relatedspec],[item])
start_dir is beginning directory. If I knew more about all this
stuff, this argument wouldn't be needed. We could find out the
current directory and use that. I accually tried that first but
it didn't seem to work (crashed). For now, just put
"pragma('D')" here when calling this routine.
filespec is the name of the file you want. It can include a
volume name and/or directories, including leading /'s to move
up from the start_dir.
defaultspec and relatedspec are optional parameters containing
all or parts of a filespec, and is supplied in the same form as
filespec. Any parts of the file name missing from filespec will
be supplied from defaultspec, then relatedspec.
item is one of: 'Volume' Volume:
'Directory' dir/
'Name' filename
'Type' .type
'File' filename.type
'c' (any
character) Volume:<c>dir/<c>filename<c>.type
(null or
missing Volume:[dir/]filename[.type]
Description
===========
Given a partial filename (ie, "file.type" or "/over1/file"),
this function will return a string containing the complete
filename, or any or all parts of the filename. Defaults may be
supplied (for any of the categories volume, directory, name, or
type) in two optional arguments.
Wildcard characters are left as found. No check is made for the
existence of any device or directory.
If you want a spec ending in a directory, be sure and include a
trailing '/'. The start_dir parameter does not need one, as it
is assumed to be a directory, and the others aren't.
Examples
========
say fparse(pragma('D'),'name','.type') ==> Work:files/name.type
say fparse(pragma('D'),'/name','.type') ==> Work:name.type
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Conditions for use and distribution
-----------------------------------
RexxExtra is Copyright (c) 1990 by Dale W. Thompson
RexxExtra is a copyrighted program that is provided "as is".
There is no warranty, either expressed or implied, as to the
quality or usefullness of the program. The user of the
program accepts all risks associated with it's use.
RexxExtra is freely distributable provided:
1. The files are included in their original form without
additions, deletions, or modifications of any kind.
2. No charge is made for RexxExtra (other than a reasonable
copy charge of $6.00 or less).
3. RexxExtra is not packaged as a part of a commercial
product.
4. RexxExtra may not be uploaded to any electronic service
that claims a copyright to it's files and programs.
Requests for additional functions
---------------------------------
The author is always looking for candidate functions to add to
the library. If you have an idea for a function or, better yet,
if you have C source code for a function you would like to see
available from ARexx, send it to me and I'll try to include it
in the next release.
Author
------
This software was developed by Dale W. Thompson from an example
library supplied on the ARexx disk (version 1.10), by William
S. Hawes. All changes and additions by me. This library was
compiled with A68K, a public domain assembler, and Lattice C
V4.0.
Any comments, questions, suggestions, flames, improvements, bug
reports (what bug? that's a feature.), etc., can be directed to
the following address:
Dale W. Thompson
542 N. 95th Circle
Mesa, AZ 85207
or you can leave me a message on one of the following boards:
AmAzing Connection - Phoenix, AZ - (602) 843-6574
Database 2000 - Phoenix, AZ - (602) 242-6734